Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 096 / confor10.arc / CONFOR.DOC next >

Wrap

Text File | 1987-05-26 | 27.5 KB | 835 lines

CONFOR.EXE - 15.1A Doorware Link for Forem PC Ver 1.00 (C) Copyright 1987 Intermountain Softworks Please study documentation for proper use May 26, 1987 Intermountain Softworks is pleased to provide a method for use of RBBS-PC Doorware (release 15.1A) with Forem PC. We've also written a similar link for PCBoard, available from us, or from many PCBoard systems around the country. CONFOR will thoroughly convince doorware applications that they are running under RBBS. For suggested sources of these programs, refer to our resource list at the end of this document. CONFOR may or may not operate as represented with a user's particular Forem PC configuration. Unfortunately, Forem PC considers a door to be an existing game or other application, with rather simple keyboard input and screen output, and of limited size and memory requirements. Forem PC remains resident while using MS-DOS redirection to operate doors. While this arrangement may adequately serve some SysOps, it is foreign to RBBS-PC Doorware and the current catalog of PCBoard doors. Doorware applications are large, stand-alone communications programs that, once invoked, expect to have a substantial amount of memory assigned to them. Available memory, with Forem PC resident, may be less than enough. Our tests were conducted with Forem PC's "small system," as distributed, 640K of RAM installed, and with no additional memory-resident utilities. Users are cordially invited to visit our own PCBoard system at 509/529-7229. Our maximum bit rate is 2400. We operate 24 hours on weekends, and between 1600h and 0600h weekdays, Pacific. Weekdays, the system is subject to availability after midnight. CONFOR.EXE - Installation and Use Table of Contents 1.0 - Acknowledgements 2 1.1 - Limited License 3 1.2 - Shareware Registration 3 1.3 - Features 4 1.4 - Version-Specific Requirements 4 1.5 - What's Needed 4 1.6 - Overview 5 2.0 - Getting Started 5 2.1 - Batch Files 6 2.2 - Disk Buffers 8 2.3 - Errors 9 3.0 - Resources 9 3.1 - A Note for Door Developers 10 Appendix A - Error Messages 11 Appendix B - CONFOR Problem Report Form 12 Appendix C - CONFOR Registration Request Form 14 1.0 - Acknowledgements Forem PC (C) 1986, 1987 Matthew R. Singer RBBS-PC (C) 1983..1987 D. Thomas Mack Microsoft, MS, and MS-DOS are registered trademarks of Microsoft Corporation. PCBoard is a trademark of Clark Development Company, Inc. PC-Write is a trademark of Quicksoft. Within the context of this document, MS-DOS and PC-DOS are equivalent. Page 2 CONFOR.EXE - Installation and Use 1.1 - Limited License The CONFOR package, consisting of CONFOR.EXE and this document, CONFOR.DOC, is the exclusive property of Intermountain Softworks, P. O. Box 2043, Walla Walla, WA 99362. The package may also include certain non-copyrighted sample data and/or batch files. Users are granted a limited license to copy and freely distribute copies of the CONFOR package, so long as the distributed copies are unmodified, the copyright notice is neither changed, removed, or bypassed, and that an unmodified copy of this documentation accompany the package. The preferred method of distribution is via one's bulletin board system. Except for the actual cost of disk media, mailer, and postage, or the normal BBS subscription fee, if any, such distribution must be without charge. Although Intermountain Softworks has exercised proper care for non-destructive operation of this product, CONFOR is offered on an "as-is" basis, without warranty, either expressed or implied. By use of this product, the user assumes all risk, to include responsi- bility for installation consistant with examples included in this document, and as promulgated by the developer of Forem PC. The libraries we use under license are fully protected by federal law, as is CONFOR. 1.2 - Shareware Registration If CONFOR provides a dependable RBBS-PC Doorware link for your system, that is to say, you continue to use it beyond a two-week evaluation period, registration is REQUIRED. This matter is NOT optional. Our modest $10 fee for use of CONFOR is little more than the price of a disk-drive cleaning kit. If you can afford Forem PC, and the hardware it requires, you can afford $10. What else does $10 buy you? Registered users will receive one year's complementary access to our PCBoard system for thirty-five minutes per day, and access to all operating doors. Our system specializes in programmers' aids and BBS support applications. It offers an alternative to busier boards, when one needs something in a hurry. There are no byte-count limits or download/upload ratios for registered users of our products. Registration also entitles one to technical support within the scope of CONFOR, via our PCBoard system. A form is included at the end of this file, for your convenience. Page 3 CONFOR.EXE - Installation and Use 1.3 - Features Automatic generation of support files. Other than RBBSxPC.DEF, which must be edited with CONFIG.EXE (ver 30.1 or later), all doorware support files are generated by CONFOR as necessary. Local mode doorware access from Forem PC. SysOps may exit to any 15.1A doorware application from the main program. Trap errorlevel within calling batch file. If CONFOR aborts for any reason (abnormal termination), an errorlevel of 3 is passed to MS-DOS. This value may be trapped within the calling batch file, for return to Forem PC. Diagnostic error messages. 1.4 - Version-Specific Requirements Many of the routines within CONFOR are hard-coded to specific bytes within the RBBS-PC 15.1A definition file(s), the messages file, and the doorware applications, or more precisely, the manner in which 15.1A doorware interprets these files. If any of these character positions changes, even the number of commas within the .DEF file, you'll need another version of CONFOR. CONFOR 1.0, therefore, does not support versions of doorware prior to 15.1A. 1.5 - What's Needed In addition to the CONFOR package, now in your possession, you'll need the RBBS-PC 15.1A configuration utility, CONFIG.EXE. This utility is analogous to SYSGEN.EXE. It also must be version 30.1 or later; earlier versions won't work. The file may be downloaded from us as CNFG301.ARC, without validation or other formality, or from any of the RBBS-PC systems cited in our resource list. Users should carefully review the instructions for implementation of doors, contained within 1_READ.ME. While not absolutely necessary, we suggest that you consider running doorware applications under MONITOR 15.1A, since this arrangement is clearly the intent of doorware's authors. MONITOR controls elapsed time (once invoked, without referencing time variables from the main program), and manages "door points" for the individual applications. Page 4 CONFOR.EXE - Installation and Use MONI151A.ARC may be downloaded from us, or from any of the systems cited in our resourse list. Additional documentation. Other than briefly noting the essential options within CONFIG.EXE, we have not made any attempt to document its operation, nor have we treated RBBS-PC file formats or network matters. We invite your attention to Tom Mack's extensive and thorough documentation for RBBS-PC 15.1A, as well as the source code for it. MS-QuickBASIC programmers should have this as a standard reference. Tom will appreciate that we borrowed his file formats (impossible to avoid, because doorware uses them), but that the "language is different." Our bps-rate detection scheme is our own. 1.6 - Overview The concept of a "door to MS-DOS" within BBS software probably originated with Tom Mack and Jon Martin as part of their RBBS-PC development. Tom writes of "horizontal growth" and adds that the term "doors" was coined to eliminate any confusion with MS-Windows. Doors are not even remotely like "Windows"; indeed, a door is little more than an exit from the BBS to a separate application, on the tenuous thread of an MS-DOS batch file. As we've previously noted, Forem PC uses a somewhat different approach, which CONFOR ignores. We suspect that Microsoft never intended batch files to be invoked remotely by BBS patrons. The vehicle, however, is provided with MS-DOS, and with careful planning and judicious use of support utilities, batch files are secure enough. 2.0 - Getting Started The first step is to have CONFIG.EXE generate an RBBS-PC.DEF file. Upon initialization, CONFIG will ask, "Will you be running multiple copies of RBBS-PC (Yes or No)?" Obviously, if running a single node, answer "no." Options which concern you are as follows: 1 - SysOps first name 2 - SysOps last name 10 - Are you using ANSI.SYS with a color monitor 16 - Name of RBBS-PC shown initially is (19 characters) 103- File RBBS builds dynamically to open a door 141- Maximum number of concurrent RBBS-PC's 201- Communications port to be used by RBBS-PC Page 5 CONFOR.EXE - Installation and Use Option 10 is analogous to "seeing what the user sees" on one's local monitor. Since the ANSI driver is already loaded, this option merely enables graphics locally within doorware. Option 103 may be any legal filename, or may remain the default of RCTTY.BAT. CONFOR strips the drive specifier from this field, and substitutes the fully qualified pathname you've supplied as a target filespec (where the messages file is written). Option 141 is exceedingly important, since CONFOR uses this value to expand the messages file to the proper number of node records. It also references this value in writing currently-logged user data to the appropriate node record. Enter 1. Option 201 tells doorware applications which COM port to use for the node in question. Messages files created by CONFIG.EXE may be deleted, since CONFOR creates its own, automatically. CONFIG's output will then be: Single node ----------- RBBS-PC.DEF This file should be copied to C:\BBS\DOORS, as further explained in the next section. 2.1 - Batch Files Within the main Forem PC directory, you'll need a text file (FDOORS.DAT) which lists available doors in a Forem-specific format. A sample of this file is supplied; line numbers in the following example are for reference only, and are further discussed below. Behind Door Number 1 is our Games Monitor 1 2 c:\bbs\d1ent.txt 3 c:\bbs\monitor.bat 4 c:\bbs\monitor1.bat 5 c:\bbs\d1ent.txt 6 Line 1 is a line of text that is displayed to the remote user upon choosing Forem main menu option J (for doors). Line 2 contains an ASCII null (00H), a carriage return (0DH), and a linefeed (0AH). The null is used to disable CTRL-C in Forem while the file is executing. How effective this may be in preventing a user from breaking out of a batch loop is a matter you'll want to determine early on. Entering a null in a text file may not be an Page 6 CONFOR.EXE - Installation and Use easy procedure for your particular text editor. We used PC-Write (tm); entered a space (20H) as a place holder, and changed it to a null with DEBUG. Line 3 is an optional text file you may wish to display before your caller actually enters the door. If none is used, the line may be blank. Line 4 is the name of the door's controlling batch file for REMOTE access. An example is included, and is reprinted below. Line 5 is the name of the door's controlling batch file for LOCAL access. CONFOR assumes that ONLY the SysOp will have local access. An example is included, and is reprinted below. Line 6 is an optional text file you may wish to display after your caller has exited the door. If none is used, the line may be blank. The contents of monitor.bat should be as follows: echo off cls c:\bbs\confor c:\bbs\forem.dat c:\bbs\doors\messages if errorlevel 3 goto exit cd\ cd\bbs\doors monitor 1 :exit CONFOR's command line arguments are few and important; indeed, "confor" entered alone at the MS-DOS prompt will display the copyright box, advise that the argument count is invalid, and abort. In normal operation, of course, a calling batch file will supply the required arguments, as suggested above. Note also that the doorware application is called with a single argument. This is the node number, and MUST be supplied as a "1" if running a single node. Observe our preferred use of fully-qualified pathnames. Some ill- behaved applications have been known to confuse MS-DOS, which normally remembers a batch file's subdirectory and last line executed. 15.1A doorware properly monitors the communications port for loss of carrier. In particular, note that C:\BBS\DOORS is the default directory for all of the support files associated with doorware. The subdirectory name may be anything, of course, but less confusion may surface if Page 7 CONFOR.EXE - Installation and Use you stick with our examples. CONFOR itself should reside in your Forem PC default directory. The contents of monitor1.bat should be as follows: echo off cls c:\bbs\confor c:\bbs\forem.dat c:\bbs\doors\messages /L if errorlevel 3 goto exit cd\ cd\bbs\doors monitor 1 :exit The ONLY difference between monitor1.bat and monitor.bat is the trailing /L in CONFOR's command line. This is for "local" operation, and allows the SysOp access from within Forem PC. The "L" is not case-sensitive, either /L or /l will work. 2.2 - Disk Buffers In the case of a CONFIG.SYS file which tells MS-DOS to trust one's judgment in a few matters, rather than reverting to defaults, most of us have safely specified FILES to equal some number, asked that MS-DOS install a RAMdisk, and have loaded the ANSI driver. Common sense may suggest that the operating system simply reads information from a disk and passes it directly to an application. This is not the case. An interim holding area, called a disk buffer, gets it first. A disk buffer is a 512-byte block of memory that MS- DOS uses to temporarily hold information it is reading from, or writing to, a disk. If the buffered data will be used repeatedly, access time will be improved significantly if MS-DOS does not have to reread the same data each time it is needed. Users are given the responsibility of telling MS-DOS how many 512-byte disk buffers to allocate. This is done within CONFIG.SYS, and uses the syntax... BUFFERS = nn where nn is an integer between 1 and 99. Each buffer requested will increase the resident size of MS-DOS by 528 bytes. Some simple algorithm could doubtless be written to suggest the optimum number of buffers for a particular configuration. For a 20- megabyte hard disk, with the number of subdirectories that PCBoard requires, the magic number, we believe, is between 15 and 25. The ultimate authority may be a stopwatch. 15 will astound you if you've Page 8 CONFOR.EXE - Installation and Use accepted the MS-DOS default of 2 or 3. Having said that, you may HAVE to accept the MS-DOS default because of space limitations. BUFFERS = 20 will increase the resident size of MS-DOS by roughly 10K, and we suspect you may need all of the space you can get to successfully operate RBBS-PC Doorware with Forem PC. 2.3 - Errors CONFOR 1.0 error messages are weighted toward the diagnostic, to include line numbers when appropriate. These will mean little to you, but will provide us with an "audit trail" of what may have happened, and where in the code it occurred. The error messages are more fully discussed in Appendix A, to include suggestions on what you might do to correct the error. If you can't resolve the problem yourself, fill out the software problem report, and either mail it to us, or upload it as SOFTPROB.xxx, where "xxx" is the first three letters of your last name. Use a "/" as the first character when PCBoard prompts for a file description. Sorry for the formality, but the report form is designed to provide us with essential information about your particular configuration, and (we hope), provide a CLEAR explanation of what you observed. Please allow us the courtesy of 24 hours for a response via our PCBoard system. If we charged $50 or $60 for CONFOR on an advance basis, we'd install an 800 number for such things. Registered users get special treatment, of course. 3.0 - Resources The five major sources of RBBS-PC doorware are... 415-689-2090 CA Concord Jon Martin 4 Home of RBBS-PC West 714-945-2612 CA Alta Loma Rod Bowman 4 PC Spectrum (tm) 701-293-5973 ND Fargo Loren Jones 4 Fargo PCUG,RBBS Beta 603-424-5497 NH Merrimack Bob Westcott 9 On-Line adventure,Ham 703-759-5049 VA Great Falls 703-759-9659 VA Great Falls Tom Mack 4 Home of RBBS-PC Page 9 CONFOR.EXE - Installation and Use 3.1 - A Note for Door Developers The following PCBoard system maintains a private conference on the subject of doors. Validation for this conference is normally extended to serious users via a C)omment to the SysOp. 201-729-7410 NJ Lake Mohawk Paul Kopit B 4 Software Soc'ty,140M Also, we attempt to stay abreast of essential utilities and tools for door applications programmers. We also have a limited number of 15.1A doorware applications available for download. Feel free to call our system during the hours indicated. Page 10 CONFOR.EXE - Installation and Use Appendix A - Error Messages CONFOR 1.0 error messages have three general formats. The most common is a single static line, followed by the usual message for an abort: Invalid argument count Abnormal program termination In some cases, the error message will report where CONFOR expected to find a certain file, and didn't: No such file or directory Abnormal program termination The rarest will include a line number: Line nnn: lseek to node record failed Abnormal program termination Here are the error conditions that you CAN do something about: Can't open file or No such file or directory CONFOR relies upon you to supply fully qualified pathnames through command line arguments within the invoking batch file. Your second argument (the target, or output, filespec) is the most critical. c:\bbs\doors\messages also tells CONFOR to look for RBBS-PC.DEF in the same location, and to write the config option 103 file in that location. "Can't open" most often means "can't find." DOS 2.00 or later version required Rare, because you wouldn't be running Forem PC with anything else. Invalid argument count Too many or too few command line arguments. See supplied batch file for an example of the proper format. Line nnn: lseek to node record failed RBBS-PC messages file is corrupted. Delete this file and let CONFOR regenerate it from scratch - automatic if file missing. CONFOR doesn't trap for everything. For example, if you were to rename a bogus file to FOREM.DAT, CONFOR won't check the file for integrity, since under normal operation, the file would have been created only a moment before by the main program. Page 11 CONFOR.EXE - Installation and Use Appendix B - CONFOR Problem Report Form Instructions: For fastest service, please complete this form with your favorite text editor, and upload to our PCBoard system as SOFTPROB.xxx, where "xxx" is the first three letters of your last name. Use a / as the first character when prompted for a description. Or, if you prefer, send hardcopy by mail. Attach additional sheets if necessary. Mailing address: PCBoard system: Intermountain Softworks 509/529-7229 P. O. Box 2043 Hours on title page Walla Walla, WA 99362 24-hour validation required for uploads Name:___________________________________ Registered user ($10 paid)? Company:________________________________ Yes [] No [] Address:________________________________ City,St,Zip:____________________________ [] Software problem Business or Data Phone:_________________ [] Documentation problem Home Phone:_____________________________ [] Other What is the three-digit VERSION number displayed in CONFOR's copyright box? ______ Computer make______________________model________cpu_________ Memory installed in kilobytes_______________________________ Version of Forem PC used:_________ Doorware version_________ Are you running doorware under MONITOR 15.1A? [] Yes [] No What SPECIFIC error messages are you getting from CONFOR? If a doorware application is resident, which one, and what error messages are you getting, if any? Please supply exact contents of FDOORS.DAT: Page 12 CONFOR.EXE - Installation and Use Appendix B - CONFOR Problem Report Form (continued) Please supply exact contents of batch file(s) that invoke(s) CONFOR: Please CLEARLY detail the problem (attach additional sheets if necessary): Please include suggestions for improvement, either in the program or the documentation. All suggestions become the property of Intermountain Softworks. Page 13 CONFOR.EXE - Installation and Use Appendix C - CONFOR Registration Request Form SEND TO: Intermountain Softworks P. O. Box 2043 Walla Walla, WA 99362 Quan Item Price Total [1.00] [ ] Diskettes $10:_____________________ [ ] Support $10:_____________________ Company P.O. +$ 5:_____________________ WA orders add 7.9%:_____________________ TOTAL (US dollars):_____________________ [] Check [] Money Order [] Company P.O. SHIP ORDER / USER MAIL / BBS VALIDATION Name:___________________________________ Company:________________________________ Address:________________________________ City,St,Zip:____________________________ Business or Data Phone:_________________ Home Phone:_____________________________ Choice of BBS password:_________________ (Limit of 12 characters, one word please!) Registered users automatically receive complementary validation on our PCBoard system, which operates 24 hours weekends, and between 1600h and 0600h Monday through Friday. On weekdays, the system is subject to availability after midnight (Pacific). 509/529-7229 No parity, 8 data bits, 1 stop bit Bit rates: 2400, 1200 Thank you! Page 14